<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">


<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    
    <title>Writing views &mdash; Django 1.7.8.dev20150401230226 documentation</title>
    
    <link rel="stylesheet" href="../../_static/default.css" type="text/css" />
    <link rel="stylesheet" href="../../_static/pygments.css" type="text/css" />
    
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    '../../',
        VERSION:     '1.7.8.dev20150401230226',
        COLLAPSE_INDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  true
      };
    </script>
    <script type="text/javascript" src="../../_static/jquery.js"></script>
    <script type="text/javascript" src="../../_static/underscore.js"></script>
    <script type="text/javascript" src="../../_static/doctools.js"></script>
    <link rel="top" title="Django 1.7.8.dev20150401230226 documentation" href="../../index.html" />
    <link rel="up" title="Handling HTTP requests" href="index.html" />
    <link rel="next" title="View decorators" href="decorators.html" />
    <link rel="prev" title="URL dispatcher" href="urls.html" />



 
<script type="text/javascript" src="../../templatebuiltins.js"></script>
<script type="text/javascript">
(function($) {
    if (!django_template_builtins) {
       // templatebuiltins.js missing, do nothing.
       return;
    }
    $(document).ready(function() {
        // Hyperlink Django template tags and filters
        var base = "../../ref/templates/builtins.html";
        if (base == "#") {
            // Special case for builtins.html itself
            base = "";
        }
        // Tags are keywords, class '.k'
        $("div.highlight\\-html\\+django span.k").each(function(i, elem) {
             var tagname = $(elem).text();
             if ($.inArray(tagname, django_template_builtins.ttags) != -1) {
                 var fragment = tagname.replace(/_/, '-');
                 $(elem).html("<a href='" + base + "#" + fragment + "'>" + tagname + "</a>");
             }
        });
        // Filters are functions, class '.nf'
        $("div.highlight\\-html\\+django span.nf").each(function(i, elem) {
             var filtername = $(elem).text();
             if ($.inArray(filtername, django_template_builtins.tfilters) != -1) {
                 var fragment = filtername.replace(/_/, '-');
                 $(elem).html("<a href='" + base + "#" + fragment + "'>" + filtername + "</a>");
             }
        });
    });
})(jQuery);
</script>


  </head>
  <body>

    <div class="document">
  <div id="custom-doc" class="yui-t6">
    <div id="hd">
      <h1><a href="../../index.html">Django 1.7.8.dev20150401230226 documentation</a></h1>
      <div id="global-nav">
        <a title="Home page" href="../../index.html">Home</a>  |
        <a title="Table of contents" href="../../contents.html">Table of contents</a>  |
        <a title="Global index" href="../../genindex.html">Index</a>  |
        <a title="Module index" href="../../py-modindex.html">Modules</a>
      </div>
      <div class="nav">
    &laquo; <a href="urls.html" title="URL dispatcher">previous</a>
     |
    <a href="../index.html" title="Using Django" accesskey="U">up</a>
   |
    <a href="decorators.html" title="View decorators">next</a> &raquo;</div>
    </div>

    <div id="bd">
      <div id="yui-main">
        <div class="yui-b">
          <div class="yui-g" id="topics-http-views">
            
  <div class="section" id="s-writing-views">
<span id="writing-views"></span><h1>Writing views<a class="headerlink" href="#writing-views" title="Permalink to this headline">¶</a></h1>
<p>A view function, or <em>view</em> for short, is simply a Python function that takes a
Web request and returns a Web response. This response can be the HTML contents
of a Web page, or a redirect, or a 404 error, or an XML document, or an image .
. . or anything, really. The view itself contains whatever arbitrary logic is
necessary to return that response. This code can live anywhere you want, as long
as it&#8217;s on your Python path. There&#8217;s no other requirement&#8211;no &#8220;magic,&#8221; so to
speak. For the sake of putting the code <em>somewhere</em>, the convention is to
put views in a file called <tt class="docutils literal"><span class="pre">views.py</span></tt>, placed in your project or
application directory.</p>
<div class="section" id="s-a-simple-view">
<span id="a-simple-view"></span><h2>A simple view<a class="headerlink" href="#a-simple-view" title="Permalink to this headline">¶</a></h2>
<p>Here&#8217;s a view that returns the current date and time, as an HTML document:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">django.http</span> <span class="kn">import</span> <span class="n">HttpResponse</span>
<span class="kn">import</span> <span class="nn">datetime</span>

<span class="k">def</span> <span class="nf">current_datetime</span><span class="p">(</span><span class="n">request</span><span class="p">):</span>
    <span class="n">now</span> <span class="o">=</span> <span class="n">datetime</span><span class="o">.</span><span class="n">datetime</span><span class="o">.</span><span class="n">now</span><span class="p">()</span>
    <span class="n">html</span> <span class="o">=</span> <span class="s">&quot;&lt;html&gt;&lt;body&gt;It is now </span><span class="si">%s</span><span class="s">.&lt;/body&gt;&lt;/html&gt;&quot;</span> <span class="o">%</span> <span class="n">now</span>
    <span class="k">return</span> <span class="n">HttpResponse</span><span class="p">(</span><span class="n">html</span><span class="p">)</span>
</pre></div>
</div>
<p>Let&#8217;s step through this code one line at a time:</p>
<ul>
<li><p class="first">First, we import the class <a class="reference internal" href="../../ref/request-response.html#django.http.HttpResponse" title="django.http.HttpResponse"><tt class="xref py py-class docutils literal"><span class="pre">HttpResponse</span></tt></a> from the
<a class="reference internal" href="../../ref/request-response.html#module-django.http" title="django.http: Classes dealing with HTTP requests and responses."><tt class="xref py py-mod docutils literal"><span class="pre">django.http</span></tt></a> module, along with Python&#8217;s <tt class="docutils literal"><span class="pre">datetime</span></tt> library.</p>
</li>
<li><p class="first">Next, we define a function called <tt class="docutils literal"><span class="pre">current_datetime</span></tt>. This is the view
function. Each view function takes an <a class="reference internal" href="../../ref/request-response.html#django.http.HttpRequest" title="django.http.HttpRequest"><tt class="xref py py-class docutils literal"><span class="pre">HttpRequest</span></tt></a>
object as its first parameter, which is typically named <tt class="docutils literal"><span class="pre">request</span></tt>.</p>
<p>Note that the name of the view function doesn&#8217;t matter; it doesn&#8217;t have to
be named in a certain way in order for Django to recognize it. We&#8217;re
calling it <tt class="docutils literal"><span class="pre">current_datetime</span></tt> here, because that name clearly indicates
what it does.</p>
</li>
<li><p class="first">The view returns an <a class="reference internal" href="../../ref/request-response.html#django.http.HttpResponse" title="django.http.HttpResponse"><tt class="xref py py-class docutils literal"><span class="pre">HttpResponse</span></tt></a> object that
contains the generated response. Each view function is responsible for
returning an <a class="reference internal" href="../../ref/request-response.html#django.http.HttpResponse" title="django.http.HttpResponse"><tt class="xref py py-class docutils literal"><span class="pre">HttpResponse</span></tt></a> object. (There are
exceptions, but we&#8217;ll get to those later.)</p>
</li>
</ul>
<div class="admonition-django-s-time-zone admonition">
<p class="first admonition-title">Django&#8217;s Time Zone</p>
<p class="last">Django includes a <a class="reference internal" href="../../ref/settings.html#std:setting-TIME_ZONE"><tt class="xref std std-setting docutils literal"><span class="pre">TIME_ZONE</span></tt></a> setting that defaults to
<tt class="docutils literal"><span class="pre">America/Chicago</span></tt>. This probably isn&#8217;t where you live, so you might want
to change it in your settings file.</p>
</div>
</div>
<div class="section" id="s-mapping-urls-to-views">
<span id="mapping-urls-to-views"></span><h2>Mapping URLs to views<a class="headerlink" href="#mapping-urls-to-views" title="Permalink to this headline">¶</a></h2>
<p>So, to recap, this view function returns an HTML page that includes the current
date and time. To display this view at a particular URL, you&#8217;ll need to create a
<em>URLconf</em>; see <a class="reference internal" href="urls.html"><em>URL dispatcher</em></a> for instructions.</p>
</div>
<div class="section" id="s-returning-errors">
<span id="returning-errors"></span><h2>Returning errors<a class="headerlink" href="#returning-errors" title="Permalink to this headline">¶</a></h2>
<p>Returning HTTP error codes in Django is easy. There are subclasses of
<a class="reference internal" href="../../ref/request-response.html#django.http.HttpResponse" title="django.http.HttpResponse"><tt class="xref py py-class docutils literal"><span class="pre">HttpResponse</span></tt></a> for a number of common HTTP status codes
other than 200 (which means <em>&#8220;OK&#8221;</em>). You can find the full list of available
subclasses in the <a class="reference internal" href="../../ref/request-response.html#ref-httpresponse-subclasses"><em>request/response</em></a>
documentation.  Just return an instance of one of those subclasses instead of
a normal <a class="reference internal" href="../../ref/request-response.html#django.http.HttpResponse" title="django.http.HttpResponse"><tt class="xref py py-class docutils literal"><span class="pre">HttpResponse</span></tt></a> in order to signify an error. For
example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">django.http</span> <span class="kn">import</span> <span class="n">HttpResponse</span><span class="p">,</span> <span class="n">HttpResponseNotFound</span>

<span class="k">def</span> <span class="nf">my_view</span><span class="p">(</span><span class="n">request</span><span class="p">):</span>
    <span class="c"># ...</span>
    <span class="k">if</span> <span class="n">foo</span><span class="p">:</span>
        <span class="k">return</span> <span class="n">HttpResponseNotFound</span><span class="p">(</span><span class="s">&#39;&lt;h1&gt;Page not found&lt;/h1&gt;&#39;</span><span class="p">)</span>
    <span class="k">else</span><span class="p">:</span>
        <span class="k">return</span> <span class="n">HttpResponse</span><span class="p">(</span><span class="s">&#39;&lt;h1&gt;Page was found&lt;/h1&gt;&#39;</span><span class="p">)</span>
</pre></div>
</div>
<p>There isn&#8217;t a specialized subclass for every possible HTTP response code,
since many of them aren&#8217;t going to be that common. However, as documented in
the <a class="reference internal" href="../../ref/request-response.html#django.http.HttpResponse" title="django.http.HttpResponse"><tt class="xref py py-class docutils literal"><span class="pre">HttpResponse</span></tt></a> documentation, you can also pass the
HTTP status code into the constructor for <a class="reference internal" href="../../ref/request-response.html#django.http.HttpResponse" title="django.http.HttpResponse"><tt class="xref py py-class docutils literal"><span class="pre">HttpResponse</span></tt></a>
to create a return class for any status code you like. For example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">django.http</span> <span class="kn">import</span> <span class="n">HttpResponse</span>

<span class="k">def</span> <span class="nf">my_view</span><span class="p">(</span><span class="n">request</span><span class="p">):</span>
    <span class="c"># ...</span>

    <span class="c"># Return a &quot;created&quot; (201) response code.</span>
    <span class="k">return</span> <span class="n">HttpResponse</span><span class="p">(</span><span class="n">status</span><span class="o">=</span><span class="mi">201</span><span class="p">)</span>
</pre></div>
</div>
<p>Because 404 errors are by far the most common HTTP error, there&#8217;s an easier way
to handle those errors.</p>
<div class="section" id="s-the-http404-exception">
<span id="the-http404-exception"></span><h3>The Http404 exception<a class="headerlink" href="#the-http404-exception" title="Permalink to this headline">¶</a></h3>
<dl class="class">
<dt id="django.http.Http404">
<em class="property">class </em><tt class="descclassname">django.http.</tt><tt class="descname">Http404</tt><a class="headerlink" href="#django.http.Http404" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>

<p>When you return an error such as <a class="reference internal" href="../../ref/request-response.html#django.http.HttpResponseNotFound" title="django.http.HttpResponseNotFound"><tt class="xref py py-class docutils literal"><span class="pre">HttpResponseNotFound</span></tt></a>,
you&#8217;re responsible for defining the HTML of the resulting error page:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">return</span> <span class="n">HttpResponseNotFound</span><span class="p">(</span><span class="s">&#39;&lt;h1&gt;Page not found&lt;/h1&gt;&#39;</span><span class="p">)</span>
</pre></div>
</div>
<p>For convenience, and because it&#8217;s a good idea to have a consistent 404 error page
across your site, Django provides an <tt class="docutils literal"><span class="pre">Http404</span></tt> exception. If you raise
<tt class="docutils literal"><span class="pre">Http404</span></tt> at any point in a view function, Django will catch it and return the
standard error page for your application, along with an HTTP error code 404.</p>
<p>Example usage:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">django.http</span> <span class="kn">import</span> <span class="n">Http404</span>
<span class="kn">from</span> <span class="nn">django.shortcuts</span> <span class="kn">import</span> <span class="n">render_to_response</span>
<span class="kn">from</span> <span class="nn">polls.models</span> <span class="kn">import</span> <span class="n">Poll</span>

<span class="k">def</span> <span class="nf">detail</span><span class="p">(</span><span class="n">request</span><span class="p">,</span> <span class="n">poll_id</span><span class="p">):</span>
    <span class="k">try</span><span class="p">:</span>
        <span class="n">p</span> <span class="o">=</span> <span class="n">Poll</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">pk</span><span class="o">=</span><span class="n">poll_id</span><span class="p">)</span>
    <span class="k">except</span> <span class="n">Poll</span><span class="o">.</span><span class="n">DoesNotExist</span><span class="p">:</span>
        <span class="k">raise</span> <span class="n">Http404</span><span class="p">(</span><span class="s">&quot;Poll does not exist&quot;</span><span class="p">)</span>
    <span class="k">return</span> <span class="n">render_to_response</span><span class="p">(</span><span class="s">&#39;polls/detail.html&#39;</span><span class="p">,</span> <span class="p">{</span><span class="s">&#39;poll&#39;</span><span class="p">:</span> <span class="n">p</span><span class="p">})</span>
</pre></div>
</div>
<p>In order to use the <tt class="docutils literal"><span class="pre">Http404</span></tt> exception to its fullest, you should create a
template that is displayed when a 404 error is raised. This template should be
called <tt class="docutils literal"><span class="pre">404.html</span></tt> and located in the top level of your template tree.</p>
<p>If you provide a message when raising an <tt class="docutils literal"><span class="pre">Http404</span></tt> exception, it will appear
in the standard 404 template displayed when <a class="reference internal" href="../../ref/settings.html#std:setting-DEBUG"><tt class="xref std std-setting docutils literal"><span class="pre">DEBUG</span></tt></a> is <tt class="docutils literal"><span class="pre">True</span></tt>. Use
these messages for debugging purposes; they generally aren&#8217;t suitable for use
in a production 404 template.</p>
</div>
</div>
<div class="section" id="s-customizing-error-views">
<span id="s-id1"></span><span id="customizing-error-views"></span><span id="id1"></span><h2>Customizing error views<a class="headerlink" href="#customizing-error-views" title="Permalink to this headline">¶</a></h2>
<p>The default error views in Django should suffice for most Web applications,
but can easily be overridden if you need any custom behavior. Simply specify
the handlers as seen below in your URLconf (setting them anywhere else will
have no effect).</p>
<p>The <a class="reference internal" href="../../ref/views.html#django.views.defaults.page_not_found" title="django.views.defaults.page_not_found"><tt class="xref py py-func docutils literal"><span class="pre">page_not_found()</span></tt></a> view is overridden by
<a class="reference internal" href="../../ref/urls.html#django.conf.urls.handler404" title="django.conf.urls.handler404"><tt class="xref py py-data docutils literal"><span class="pre">handler404</span></tt></a>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">handler404</span> <span class="o">=</span> <span class="s">&#39;mysite.views.my_custom_page_not_found_view&#39;</span>
</pre></div>
</div>
<p>The <a class="reference internal" href="../../ref/views.html#django.views.defaults.server_error" title="django.views.defaults.server_error"><tt class="xref py py-func docutils literal"><span class="pre">server_error()</span></tt></a> view is overridden by
<a class="reference internal" href="../../ref/urls.html#django.conf.urls.handler500" title="django.conf.urls.handler500"><tt class="xref py py-data docutils literal"><span class="pre">handler500</span></tt></a>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">handler500</span> <span class="o">=</span> <span class="s">&#39;mysite.views.my_custom_error_view&#39;</span>
</pre></div>
</div>
<p>The <a class="reference internal" href="../../ref/views.html#django.views.defaults.permission_denied" title="django.views.defaults.permission_denied"><tt class="xref py py-func docutils literal"><span class="pre">permission_denied()</span></tt></a> view is overridden by
<a class="reference internal" href="../../ref/urls.html#django.conf.urls.handler403" title="django.conf.urls.handler403"><tt class="xref py py-data docutils literal"><span class="pre">handler403</span></tt></a>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">handler403</span> <span class="o">=</span> <span class="s">&#39;mysite.views.my_custom_permission_denied_view&#39;</span>
</pre></div>
</div>
<p>The <a class="reference internal" href="../../ref/views.html#django.views.defaults.bad_request" title="django.views.defaults.bad_request"><tt class="xref py py-func docutils literal"><span class="pre">bad_request()</span></tt></a> view is overridden by
<a class="reference internal" href="../../ref/urls.html#django.conf.urls.handler400" title="django.conf.urls.handler400"><tt class="xref py py-data docutils literal"><span class="pre">handler400</span></tt></a>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">handler400</span> <span class="o">=</span> <span class="s">&#39;mysite.views.my_custom_bad_request_view&#39;</span>
</pre></div>
</div>
</div>
</div>


          </div>
        </div>
      </div>
      
        
          <div class="yui-b" id="sidebar">
            
      <div class="sphinxsidebar">
        <div class="sphinxsidebarwrapper">
  <h3><a href="../../contents.html">Table Of Contents</a></h3>
  <ul>
<li><a class="reference internal" href="#">Writing views</a><ul>
<li><a class="reference internal" href="#a-simple-view">A simple view</a></li>
<li><a class="reference internal" href="#mapping-urls-to-views">Mapping URLs to views</a></li>
<li><a class="reference internal" href="#returning-errors">Returning errors</a><ul>
<li><a class="reference internal" href="#the-http404-exception">The Http404 exception</a></li>
</ul>
</li>
<li><a class="reference internal" href="#customizing-error-views">Customizing error views</a></li>
</ul>
</li>
</ul>

  <h3>Browse</h3>
  <ul>
    
      <li>Prev: <a href="urls.html">URL dispatcher</a></li>
    
    
      <li>Next: <a href="decorators.html">View decorators</a></li>
    
  </ul>
  <h3>You are here:</h3>
  <ul>
      <li>
        <a href="../../index.html">Django 1.7.8.dev20150401230226 documentation</a>
        
          <ul><li><a href="../index.html">Using Django</a>
        
          <ul><li><a href="index.html">Handling HTTP requests</a>
        
        <ul><li>Writing views</li></ul>
        </li></ul></li></ul>
      </li>
  </ul>

  <h3>This Page</h3>
  <ul class="this-page-menu">
    <li><a href="../../_sources/topics/http/views.txt"
           rel="nofollow">Show Source</a></li>
  </ul>
<div id="searchbox" style="display: none">
  <h3>Quick search</h3>
    <form class="search" action="../../search.html" method="get">
      <input type="text" name="q" />
      <input type="submit" value="Go" />
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
    <p class="searchtip" style="font-size: 90%">
    Enter search terms or a module, class or function name.
    </p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
              <h3>Last update:</h3>
              <p class="topless">Apr 02, 2015</p>
          </div>
        
      
    </div>

    <div id="ft">
      <div class="nav">
    &laquo; <a href="urls.html" title="URL dispatcher">previous</a>
     |
    <a href="../index.html" title="Using Django" accesskey="U">up</a>
   |
    <a href="decorators.html" title="View decorators">next</a> &raquo;</div>
    </div>
  </div>

      <div class="clearer"></div>
    </div>
  </body>
</html>